DigiLocker Consent URL API

The following document highlights the details of the DigiLocker Consent URL API.

API Description

Objective

The DigiLocker Consent URL API, also known as the Start API, initiates the customer consent-seeking process through a URL that grants HyperVerge the access to the documents within their DigiLocker account.

Input	Output
A unique reference identifier and redirect URL to initiate the DigiLocker consent process	A consent URL that grants HyperVerge access to documents within the user's DigiLocker account

API URL

https://ind-verify.hyperverge.co/api/digilocker/start

API Endpoint

start

Overview

The DigiLocker Consent URL API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Optional	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the DigiLocker Consent URL API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
referenceId	Mandatory	string	The unique reference identifier	Not Applicable	Not Applicable
redirectURL	Optional	string	The URL to which the user will be redirected after completion	Not Applicable	Not Applicable
flow	Optional	string	The parameter enables you to direct users to Sign In or Sign Up screens	Not Applicable	Not Applicable
useCustomAuthFlow	Optional	string	The parameter to enable the custom authorization flow. When set to yes, users are directed to your custom authorization flow instead of HyperVerge default screens. The parameter is recommended to maintain a consistent user experience within your application	Not Applicable	no
usePinlessAuth	Optional	string	The parameter to enable DigiLocker PIN-less authentication. When set to yes, users can authenticate without entering a PIN	Not Applicable	Not Applicable
returnSummary	Optional	string	The parameter to control whether a summary is returned in the response. When set to yes, the API response includes a summary	Not Applicable	Not Applicable
enableDarkMode	Optional	string	The parameter to enable the HyperVerge SDK dark mode. When set to yes, the SDK screen displays in dark mode	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the DigiLocker Consent URL API:

curl --location --request POST 'https://ind-verify.hyperverge.co/api/digilocker/start' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data-raw '{
    "referenceId": "<Enter_the_Reference_ID>",
    "redirectURL": "<Enter_the_Redirect_URL>",
    "useCustomAuthFlow": "<Enter_yes_or_no>",
    "usePinlessAuth": "<Enter_yes_or_no>",
    "flow": "<signin_or_signup>"
}'

Success Response

The following code snippet demonstrates a success response from the DigiLocker Consent URL API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "url": "<The_consent_URL_string>"
  }
}

Success Response Details

The following table outlines the details of the success response from the DigiLocker Consent URL API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code for the response
result	object	The JSON object containing the consent URL
result.url	string	The DigiLocker URL that seeks permission from the customer to provide HyperVerge with the consent to access their documents

info

For Sign In flows, if a user has already completed the flow and provided full consent to all documents in the consent screen, DigiLocker caches this consent for 15 minutes.
During this period, if the user initiates another Sign In flow, they will bypass the consent screen as the system recognizes that full consent has already been provided for all documents. Users won't see the consent screen again until the 15-minute cache period expires or if they attempt to access documents that weren't previously consented to.

Error Responses

The following are some error responses from the DigiLocker Consent URL API:

Missing or Invalid Credentials

{
    "status": "failure",
    "statusCode": "401",
    "error": "Missing/Invalid credentials"
}

Bad Request - Missing referenceId

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "referenceId is required"
  }
}

Bad Request - Metadata Not Found

{
  "status": "failure",
  "statusCode": "400",
  "error": "Metadata for key - digilocker with appid - <<application ID>> does not exists"
}

Server Error

{
  "status": "failure",
  "statusCode": "500",
  "error": {
    "code": "ER_SERVER",
    "message": "Something went wrong"
  }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	ER_REQ_VALIDATE / Bad Request	The request is missing required parameters or has invalid values, or metadata for DigiLocker credentials does not exist	Provide all mandatory parameters in the request or ensure DigiLocker credentials are configured using the Credentials API
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
500	Internal Server Error	There was an error with HyperVerge's server	Please check the request headers or contact the HyperVerge team for resolution

PIN-less Authentication

The following section provides a detailed explanation of DigiLocker PIN-less authentication and how it works.

What is PIN-less flow?

The DigiLocker PIN-less flow enables end users to retrieve their identity documents without requiring a six-digit Security PIN during authentication. This flow bypasses the standard PIN-based authentication mechanism by leveraging Single Sign-On (SSO) integration. It is Implemented through integration with the MeriPehchaan platform

Enable PIN-less Flow

To enable PIN-less authentication, set the parameter usePinlessAuth to yes in the API request body.

Use Case

The PIN-less flow is optimized for streamlining the sign-in process for existing DigiLocker users. By eliminating the need to enter a six-digit Security PIN, it significantly reduces authentication friction and enables faster access to documents. Users who already have documents stored in their DigiLocker account can leverage this flow for quick sign-in and document retrieval.

Note: The sign-up journey via PIN-less flow does not include UIDAI or NSDL integration, so document fetching during initial account creation is not available.

PIN-less vs PIN-based Authentication

The following table compares the key differences between PIN-based and PIN-less authentication flows:

Feature	PIN-based Flow	PIN-less Flow
Purpose	Used for signing-in, signing-up, and fetching new documents from issuing authorities like UIDAI/NSDL	Simplifies sign-in to fetch documents already in the Digilocker Vault
Authentication Method	Requires a six-digit security PIN for validation	No PIN is required; leverages Single Sign-On (SSO) via the MeriPehchaan platform
Document Fetching	Supports fetching new Aadhaar/PAN/DL cards from issuing authorities	Limited to fetching Aadhaar/PAN/DL cards already present in the Digilocker Vault
Limitations	Requires users to remember and enter the PIN	Does not support document fetching during sign-up or new document access
Advantages	Full functionality for onboarding and document retrieval	Enhanced user convenience and faster sign-in experience

PIN-less Flow Demo

The following demo video illustrates the DigiLocker PIN-less authentication flow with example UI screens:

PIN-less Authentication and Sign Up Flow

We strongly discourage using the combination of PIN-less authentication (usePinlessAuth: "yes") with the Sign Up flow (flow: "signup").

The PIN-less flow is optimized for existing DigiLocker users who already have documents in their account, and it does not support document fetching during the sign-up process. Using this combination can result in a suboptimal user experience and may prevent successful document retrieval.

Recommended approach: Orchestrate the authentication flow based on user type. Use PIN-less authentication for existing users (sign-in flow) and PIN-based authentication for new users (sign-up flow) to ensure optimal functionality and user experience.